---
title: Fetching and Filtering Tools
image: "https://og.composio.dev/api/og?title=Fetching%20and%20Filtering%20Tools"   # image for socials
keywords: "fetch tool, filter tool"
subtitle: "Learn how to fetch and filter Composio's tools and toolsets"
hide-nav-links: false
---

To effectively use tools, it is recommended to fetch, inspect, and filter them based on your criteria. 

This process returns a union of all tools that match the specified criteria, ensuring you provide the most relevant tools to the agents.

When fetching tools, they are automatically formatted to match the requirements of the provider you are using. This means you do not need to manually convert or adapt the tool format.

## Filtering by toolkit
Toolkits are collections of tools from a specific app!

Fetching tools from a toolkit is a good way to get a sense of the tools available.

<Tip title="Tools are ordered by importance" icon="info">
When you fetch tools from a toolkit, the most important tools are returned first.

Composio determines the importance of a tool based on the usage and relevance of the tool.
</Tip>

<CodeGroup>
```python Python maxLines=60 wordWrap
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB", "HACKERNEWS"],
)
```

```typescript TypeScript maxLines=60 wordWrap
const tools = await composio.tools.get(
  userId,
  {
    toolkits: ["GITHUB", "LINEAR"],
  }
);
```
</CodeGroup>

**Limiting the results**

Multiple toolkits have 100s of tools. These can easily overwhelm the LLM. Hence, the SDK allows you to limit the number of tools returned.

The default `limit` is 20 -- meaning you get the top 20 important tools from the toolkit.

<CodeGroup>
```python Python maxLines=60 wordWrap
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"],
    limit=5,  # Returns the top 5 important tools from the toolkit
)
```
```typescript TypeScript maxLines=60 wordWrap
const tools = await composio.tools.get(userId, {
  toolkits: ["GITHUB"],
  limit: 5, // Returns the top 5 important tools from the toolkit
});
```
</CodeGroup>

**Filtering by scopes**

When working with OAuth-based toolkits, you can filter tools based on their required scopes. This is useful when you want to:
- Get tools that match specific permission levels
- Ensure tools align with available user permissions
- Filter tools based on their required OAuth scopes

<Tip title="Single Toolkit Requirement" icon="warning">
Scope filtering can only be used with a single toolkit at a time.
</Tip>

<CodeGroup>
```python Python maxLines=60 wordWrap
# Get GitHub tools that require specific scopes
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"],
    scopes=["repo"],  # Only get tools requiring these scopes
    limit=10
)
```
```typescript TypeScript maxLines=60 wordWrap
// Get GitHub tools that require specific scopes
const tools = await composio.tools.get(userId, {
  toolkits: ["GITHUB"],
  scopes: ["repo"],  // Only get tools requiring these scopes
  limit: 10
});
```
</CodeGroup>

## Tool versions

You can configure toolkit versions at SDK initialization to ensure consistent tool behavior across environments. When fetching tools, you can also [inspect which version each tool is using](/docs/toolkit-versioning#inspect-current-versions).

## Filtering by tool
You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools [here](/tools) to view and inspect the tools for each toolkit.

<CodeGroup>

```python Python maxLines=60 wordWrap
tools = composio.tools.get(
    user_id,
    tools=[
        "GITHUB_CREATE_AN_ISSUE",
        "GITHUB_CREATE_AN_ISSUE_COMMENT",
        "GITHUB_CREATE_A_COMMIT",
    ],
)
```

```typescript TypeScript maxLines=60 wordWrap
const tools = await composio.tools.get(userId, {
  tools: [
    "GITHUB_CREATE_AN_ISSUE",
    "GITHUB_CREATE_AN_ISSUE_COMMENT",
    "GITHUB_CREATE_A_COMMIT",
  ],
});
```
</CodeGroup>

## Fetching raw tools
To examine the raw schema definition of a tool to understand the input/output parameters or to build custom logic around tool definitions, you can use the following methods. This can be useful for:
- Understanding exact input parameters and output structures.
- Building custom logic around tool definitions.
- Debugging tool interactions.
- Research and experimentation.

<CodeGroup>
<SnippetCode 
  src="fern/snippets/tool-calling/python/raw_tools.py"
  startLine={5}
  endLine={7}
  title="Python"
/>
<SnippetCode 
  src="fern/snippets/tool-calling/typescript/raw_tools.ts"
  startLine={5}
  endLine={7}
  title="TypeScript"
/>
</CodeGroup>


## Filtering by search (Experimental)
You may also filter tools by searching for them. This is a good way to find tools that are relevant to a given use case.

This step runs a semantic search on the tool names and descriptions and returns the most relevant tools.

<CodeGroup>
```python Python maxLines=60 wordWrap
tools = composio.tools.get(
    user_id,
    search="hubspot organize contacts",
)

# Search within a specific toolkit
tools = composio.tools.get(
    user_id,
    search="repository issues",
    toolkits=["GITHUB"],  # Optional: limit search to specific toolkit
    limit=5  # Optional: limit number of results
)
```

```typescript TypeScript maxLines=60 wordWrap
const tools = await composio.tools.get(userId, {
  search: "hubspot organize contacts",
});

// Search within a specific toolkit
const tools = await composio.tools.get(userId, {
  search: "repository issues",
  toolkits: ["GITHUB"],  // Optional: limit search to specific toolkit
  limit: 5  // Optional: limit number of results
});
```
</CodeGroup>

## Filter Combinations

When fetching tools, you must use one of these filter combinations:

1. **Tools Only**: Fetch specific tools by their slugs
   ```typescript
   { tools: ["TOOL_1", "TOOL_2"] }
   ```

2. **Toolkits Only**: Fetch tools from specific toolkits
   ```typescript
   { toolkits: ["TOOLKIT_1", "TOOLKIT_2"], limit?: number }
   ```

3. **Single Toolkit with Scopes**: Fetch tools requiring specific OAuth scopes
   ```typescript
   { toolkits: ["GITHUB"], scopes: ["read:repo"], limit?: number }
   ```

4. **Search**: Search across all tools or within specific toolkits
   ```typescript
   { search: "query", toolkits?: string[], limit?: number }
   ```

These combinations are mutually exclusive - you can't mix `tools` with `search` or use `scopes` with multiple toolkits.